import { Code, InlineCode } from '~/components/text/code'
import { HelpLink } from '~/components/text/link'
import Note from '~/components/text/note'
import Endpoint from '~/components/api/endpoint'
import Request from '~/components/api/request'

export const meta = {
  editUrl: 'pages/docs/api/v2/api-docs-mdx/endpoints/secrets.mdx',
  lastEdited: '2019-10-17T14:44:04.000Z'
}

## Secrets

### List all the secrets

<Endpoint method="GET" url="/v2/now/secrets" />

Retrieves all of the active now secrets for the authenticating user.
The body will contain an entry for each secret.

#### Response Parameters

| Key         | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Description                 |
| ----------- | ---------------------------------------------------------- | --------------------------- |
| **secrets** | <HelpLink href="#api-basics/types">List</HelpLink>         | The list of active secrets. |

#### Secret

This is the format of each item in the `secrets` list.

| Key         | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Description                                                                                   |
| ----------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **uid**     | <HelpLink href="#api-basics/types">ID</HelpLink>           | The unique identifier of the secret. Always prepended with `sec_`.                            |
| **name**    | <HelpLink href="#api-basics/types">String</HelpLink>       | The name of the secret. This is what you could use in your environment variables after a `@`. |
| **created** | <HelpLink href="#api-basics/types">Date</HelpLink>         | The date when the secret was created.                                                         |

##### Example Request

<Request url="https://api.zeit.co/v2/now/secrets" auth />

##### Example Response

<Code lang="json">{`{
  "secrets": [
    {
      "uid": "sec_T70JHBhR1gqaxXVrLTsHr6B9",
      "name": "guillermo",
      "created": "2016-09-02T01:03:50.000Z"
    }
  ]
}`}</Code>

### Create a new secret

<Endpoint method="POST" url="/v2/now/secrets" />

Creates a new secret. The body should contain `name` and `value` strings.

<Note>The name of the secret couldn't be bigger than 100 characters.</Note>

#### Request Parameters

| Key       | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                                  |
| --------- | ---------------------------------------------------------- | -------- | -------------------------------------------- |
| **name**  | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | The name of the secret (max 100 characters). |
| **value** | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | The value of the new secret.                 |

#### Response Parameters

| Key         | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Description                                                        |
| ----------- | ---------------------------------------------------------- | ------------------------------------------------------------------ |
| **uid**     | <HelpLink href="#api-basics/types">ID</HelpLink>           | The unique identifier of the secret. Always prepended with `sec_`. |
| **name**    | <HelpLink href="#api-basics/types">String</HelpLink>       | The name of the secret.                                            |
| **created** | <HelpLink href="#api-basics/types">Date</HelpLink>         | The date when the secret was created.                              |
| **userId**  | <HelpLink href="#api-basics/types">ID</HelpLink>           | The unique identifier of the user who created the secret.          |
| **value**   | <HelpLink href="#api-basics/types">Map</HelpLink>          | A map with the value of the secret.                                |

#### Secret value

This is the format of the Map received as `value`.

| Key      | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Description                                                            |
| -------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- |
| **type** | <HelpLink href="#api-basics/types">String</HelpLink>       | The type of structure used to save the secret value (always `Buffer`). |
| **data** | <HelpLink href="#api-basics/types">List</HelpLink>         | A list of numbers which could be used to recreate the secret value.    |

##### Example Request

<Request
  method="POST"
  url="https://api.zeit.co/v2/now/secrets"
  headers={{
    'Content-Type': 'application/json'
  }}
  auth
  body={{
    name: 'my-api-key',
    value: 'my-value'
  }}
/>

##### Example Response

<Code lang="json">{`{
  "uid": "sec_XCG7t7AIHuO2SBA8667zNUiM",
  "name": "my-api-key",
  "created": "2017-09-22T13:11:49.180Z",
  "userId": "kr1PsOIzqEL5Xg6M4VZcZosf",
  "value": {
    "type": "Buffer",
    "data": [
      109,
      121,
      45,
      118,
      97,
      108,
      117,
      101
    ]
  }
}`}</Code>

### Change secret name

<Endpoint method="PATCH" url="/v2/now/secrets/:name" />

This endpoint provides an opportunity to edit the `name`
of a user's secret. The name has to be unique to that user's secrets.

The body must contain a field `name` with the new name to use.

#### Request Parameters

| Key      | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Required | Description                 |
| -------- | ---------------------------------------------------------- | -------- | --------------------------- |
| **name** | <HelpLink href="#api-basics/types">String</HelpLink>       | Yes      | The new name of the secret. |

#### Response Parameters

| Key         | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Description                                                        |
| ----------- | ---------------------------------------------------------- | ------------------------------------------------------------------ |
| **uid**     | <HelpLink href="#api-basics/types">ID</HelpLink>           | The unique identifier of the secret. Always prepended with `sec_`. |
| **name**    | <HelpLink href="#api-basics/types">String</HelpLink>       | The new name of the secret.                                        |
| **created** | <HelpLink href="#api-basics/types">Date</HelpLink>         | The date when the secret was created.                              |
| **oldName** | <HelpLink href="#api-basics/types">String</HelpLink>       | The old name of the secret.                                        |

##### Example Request

<Request
  method="PATCH"
  url="https://api.zeit.co/v2/now/secrets/my-api-key"
  headers={{
    'Content-Type': 'application/json'
  }}
  auth
  body={{
    name: 'my-renamed-api-key'
  }}
/>

##### Example Response

<Code lang="json">{`{
  "uid": "sec_XCG7t7AIHuO2SBA8667zNUiM",
  "name": "my-api-key",
  "created": "2017-09-22T13:11:49.180Z",
  "oldName": "my-api-key"
}`}</Code>

The `uid` returned is that of the matched secret.

### Delete a secret

<Endpoint method="DELETE" url="/v2/now/secrets/:name" />

This deletes the user's secret defined in the URL.

#### Response Parameters

| Key         | <HelpLink href="#api-basics/types" hasIcon>Type</HelpLink> | Description                                                        |
| ----------- | ---------------------------------------------------------- | ------------------------------------------------------------------ |
| **uid**     | <HelpLink href="#api-basics/types">ID</HelpLink>           | The unique identifier of the secret. Always prepended with `sec_`. |
| **name**    | <HelpLink href="#api-basics/types">String</HelpLink>       | The name of the secret.                                            |
| **created** | <HelpLink href="#api-basics/types">Date</HelpLink>         | The date when the secret was created.                              |

##### Example Request

<Request
  method="DELETE"
  url="https://api.zeit.co/v2/now/secrets/my-renamed-api-key"
  auth
/>

##### Example Response

<Code lang="json">{`{
  "uid": "sec_XCG7t7AIHuO2SBA8667zNUiM",
  "name": "my-renamed-api-key",
  "created": "2017-09-22T13:11:49.180Z"
}`}</Code>

The `uid` returned is that of the matched secret.
